Running, Building, and Troubleshooting the First Android App

Course: Android App Development

Topic: Running, Building, and Troubleshooting the First Android App

Course Link: Android App Development Course – JustAcademy

Demo Link: Register for a Course Demo

Website: JustAcademy Homepage

1. Introduction

Building and running an Android application are essential steps in the Android development process. After creating an Android project in Android Studio, developers must compile the source code, resolve dependencies, package the application, install it on a device, and verify that it works correctly.

Android Studio provides an integrated development environment (IDE) that supports code editing, project building, application deployment, debugging, and error analysis. It works with the Gradle build system to compile source files, process resources, manage dependencies, and generate application packages.

For beginners, the first application is an opportunity to understand the complete development workflow. Even a simple application can introduce important concepts such as project structure, Kotlin code, XML resources, Android manifests, build configurations, emulator testing, and troubleshooting.

2. Learning Objectives

• Understand the Android application build and execution process.
• Learn the difference between building, running, and debugging an app.
• Understand the role of Android Studio and Gradle.
• Create and run a basic Android application.
• Build an APK for testing purposes.
• Identify common compilation, synchronization, installation, and runtime errors.
• Use Build Output and Logcat to investigate problems.
• Apply debugging techniques to resolve issues efficiently.

3. Understanding the Android Development Workflow

Android application development follows a sequence of steps that transforms source code into an executable application.

1. Create the project: Set up the application name, package identifier, programming language, and minimum SDK.
2. Write the code: Create the user interface and application logic using Kotlin, Java, XML, or supported UI frameworks.
3. Synchronize Gradle: Resolve build configuration and dependency information.
4. Build the project: Compile code, process resources, and package the application.
5. Choose a target device: Select an Android Emulator or a connected physical Android device.
6. Install the application: Deploy the generated application package to the target device.
7. Run the application: Launch the app and interact with its features.
8. Test and debug: Inspect errors, fix problems, rebuild, and test again.

Workflow Overview

Create Android Project
        |
        v
Write Code and Resources
        |
        v
Sync Gradle and Dependencies
        |
        v
Build the Application
        |
        v
Select Emulator or Device
        |
        v
Install and Launch the App
        |
        v
Test, Debug, and Fix Errors
        |
        v
Build and Test Again

4. What Is Building an Android Application?

Building an Android application means processing the project's source code, resources, dependencies, and configuration files to produce an application package or another build artifact.

Android Studio coordinates many of these operations through Gradle and the Android Gradle Plugin.

Major Build Activities

5. What Is Gradle in Android Development?

Gradle is a build automation system used to define and execute tasks required to build an Android project. The Android Gradle Plugin integrates Android-specific build operations with Gradle.

Gradle configuration files specify plugin versions, SDK settings, dependencies, build types, and other project options.

Common Gradle Files

Important Gradle Tasks

Available tasks can vary depending on the project, plugins, modules, and build configuration.

6. Understanding Debug and Release Builds

Android projects commonly provide debug and release build types. Each build type serves a different purpose.

When you click Run in Android Studio, the IDE normally deploys a debug version of the app. A release build should be tested separately before distribution because its optimization, signing, and configuration may differ.

7. Preparing the First Android Application

Before running the app, make sure the development environment and project are ready.

• Install Android Studio.
• Install the Android SDK and a compatible SDK platform.
• Open or create an Android project.
• Wait for Gradle synchronization to complete.
• Resolve any errors shown in the editor or Build tool window.
• Create an Android Virtual Device or connect a physical device.

Verify the Project Structure

MyFirstAndroidApp/
├── app/
│   ├── src/
│   │   └── main/
│   │       ├── AndroidManifest.xml
│   │       ├── java/ or kotlin/
│   │       └── res/
│   └── build.gradle.kts
├── gradle/
├── build.gradle.kts
├── settings.gradle.kts
├── gradlew
└── gradlew.bat

This is a representative project structure. Exact folders and files vary by Android Studio template, programming language, UI framework, and Gradle configuration.

8. Creating a Simple Android Application

Android Studio can generate a starter project with the required files and configuration. For this example, create a basic Android application using Kotlin.

Step 1: Create the Project

1. Open Android Studio.
2. Select the option to create a new project.
3. Choose a phone or tablet template, such as an Empty Activity.
4. Enter a project name, for example MyFirstAndroidApp.
5. Select Kotlin if the template asks for a programming language.
6. Choose a minimum SDK appropriate for the project.
7. Click Finish and wait for the project to load.

Step 2: Add a Simple User Interface

Many current Android Studio templates use Jetpack Compose. The following example shows a simple Compose screen. Place it in the generated Activity file only if the selected project template uses Compose and has the required imports and dependencies.

package com.example.myfirstandroidapp

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.material3.Button
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.runtime.*
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContent {
            MaterialTheme {
                FirstAppScreen()
            }
        }
    }
}

@Composable
fun FirstAppScreen() {
    var message by remember {
        mutableStateOf("Welcome to Android Development!")
    }

    Column(
        modifier = Modifier.fillMaxSize(),
        horizontalAlignment = Alignment.CenterHorizontally,
        verticalArrangement = Arrangement.Center
    ) {
        Text(text = message)
        Button(onClick = {
            message = "Your first app is running!"
        }) {
            Text("Click Me")
        }
    }
}

Important: The package declaration must match your project's package structure. Existing starter templates may already include a theme, imports, or generated UI code. Adapt the example to the files created by your selected template rather than replacing unrelated project configuration.

Step 3: Understand the Code

9. Building the First Android App

Building verifies whether the project can be compiled and packaged with the current configuration. You can build the app without launching it on a device.

Build Using Android Studio

1. Open the Android project.
2. Wait for Gradle synchronization to finish.
3. Check the selected build variant if the project has multiple variants.
4. Open the Build menu.
5. Select the appropriate build action, such as Make Project or the relevant module build task, depending on your Android Studio version.
6. Wait for the build process to finish.
7. Review the Build Output window for success or failure details.

Build a Debug APK Using the Gradle Wrapper

You can also build a debug APK from the command line. Open a terminal at the project root and run the appropriate command.

Windows:

gradlew.bat assembleDebug

macOS or Linux:

./gradlew assembleDebug

The command uses the project's Gradle Wrapper and build configuration. If the build succeeds, the APK is commonly generated at:

app/build/outputs/apk/debug/app-debug.apk

The exact output path and filename may differ for projects with multiple modules, product flavors, or custom build settings.

10. Running the App on an Android Emulator

An Android Emulator allows you to test an application without connecting a physical phone. The emulator must have a compatible Android Virtual Device configured.

1. Open Device Manager in Android Studio.
2. Create a virtual device if one does not already exist.
3. Choose a hardware profile and download a compatible system image.
4. Launch the emulator and wait for Android to finish booting.
5. Return to your project in Android Studio.
6. Select the app run configuration.
7. Choose the running emulator from the target-device menu.
8. Click the Run button.
9. Wait for Android Studio to build, install, and launch the app.

When the app starts, verify that the expected screen appears and that buttons, text, navigation, and other implemented features behave correctly.

11. Running the App on a Physical Android Device

A physical device provides an additional testing environment and can reveal hardware or manufacturer-specific behavior that an emulator may not reproduce.

Steps to Connect a Device

1. Enable Developer Options on the Android phone if they are not already enabled.
2. Enable USB debugging in Developer Options.
3. Connect the phone to the computer with a data-capable USB cable.
4. Approve the USB debugging authorization prompt on the phone.
5. Confirm that Android Studio recognizes the device.
6. Select the phone from the target-device menu.
7. Click Run to build, install, and launch the app.

Menu names can vary by device manufacturer and Android version. Only authorize debugging on computers you trust.

12. Installing an APK Manually

If you have already generated an APK, you can install it on a compatible emulator or connected device. Manual installation is useful for testing a built package separately from the IDE deployment workflow.

Using Android Debug Bridge (ADB)

ADB is a command-line tool included with Android SDK Platform-Tools. With a connected device or running emulator, you can check available devices:

adb devices

Install a debug APK using:

adb install app/build/outputs/apk/debug/app-debug.apk

If the application is already installed and you want to reinstall a compatible build, the following command may be useful:

adb install -r app/build/outputs/apk/debug/app-debug.apk

The -r option requests reinstallation while retaining application data when the package and signing requirements permit it. Installation can still fail because of signature conflicts, version incompatibilities, or other device restrictions.

13. Understanding the Build Output Window

The Build tool window is one of the most important places to investigate build failures. It displays Gradle tasks, synchronization messages, compiler errors, and other build information.

To open it, use View > Tool Windows > Build or the corresponding Build window entry in your Android Studio version.

How to Read Build Errors

1. Locate the first meaningful error message in the failed build output.
2. Read the file path, line number, task name, and error description.
3. Open the referenced source or configuration file.
4. Fix the underlying problem rather than changing unrelated files.
5. Run the build again and check whether the original error is resolved.

A build may display several errors because one underlying issue causes additional failures. Resolve the earliest relevant error first, then rebuild to determine which issues remain.

14. Understanding Logcat

Logcat displays system and application log messages from a connected emulator or device. It is especially useful when an application builds successfully but crashes, freezes, or behaves unexpectedly at runtime.

Common Logcat Uses

• Identify exceptions and stack traces.
• Locate application crash messages.
• Inspect log messages written by your code.
• Filter logs by package, process, or severity.
• Investigate lifecycle and runtime behavior.

Open Logcat through the relevant tool window in Android Studio. Select the correct device and application process, then reproduce the problem. Search for the exception type and inspect the stack trace to locate the relevant application code.

Example: Adding a Log Message in Kotlin

import android.util.Log

Log.d("MainActivity", "The screen has been created")

The message can be filtered in Logcat using the tag MainActivity. Use log levels appropriately and avoid logging passwords, access tokens, or other sensitive information.

15. Common Build Errors and Their Solutions

16. Troubleshooting Application Installation Problems

Sometimes a project builds successfully but the app fails to install on the selected device.

17. Troubleshooting Runtime Crashes

A runtime crash occurs when an application starts executing but encounters an unhandled error or another condition that causes it to terminate.

Common Causes

• Null references or unexpected null values.
• Incorrect type conversions or invalid data.
• Missing runtime permissions.
• Incorrect Activity or component configuration.
• Invalid navigation or lifecycle handling.
• Network failures that are not handled correctly.
• Accessing resources that do not exist.
• Exceptions thrown by third-party libraries or application code.

Systematic Debugging Process

1. Reproduce the crash using the same steps.
2. Open Logcat and select the correct application process.
3. Find the fatal exception or relevant error message.
4. Read the stack trace and identify the first application code location involved.
5. Inspect the variable values and surrounding logic.
6. Set a breakpoint if necessary and run the app in Debug mode.
7. Fix the cause, rebuild, and repeat the test.

18. Using Breakpoints and the Debugger

The Android Studio debugger helps developers examine application execution while the program is running.

How to Use a Breakpoint

1. Open a Kotlin or Java source file.
2. Click beside a line number to place a breakpoint.
3. Click Debug instead of Run.
4. Perform the action that executes the selected line.
5. When execution pauses, inspect variables and the call stack.
6. Use Step Over, Step Into, Step Out, or Resume to continue execution.

19. Understanding AndroidManifest.xml

The Android manifest describes important application information to the Android build tools and operating system. Depending on the application, it may declare components, permissions, features, and other configuration details.

For example, a modern application might contain an Activity declaration similar to the following. This is an illustrative excerpt; use the manifest generated by your project and do not replace its complete contents without checking the existing configuration.

<application
    android:label="My First App"
    android:theme="@style/Theme.MyFirstAndroidApp">
    <activity
        android:name=".MainActivity"
        android:exported="true">
        <intent-filter>
            <action android:name="android.intent.action.MAIN" />
            <category android:name="android.intent.category.LAUNCHER" />
        </intent-filter>
    </activity>
</application>

The example assumes that the theme resource exists and that the Activity's name is correct. For an Activity with a launcher intent filter, explicitly configuring android:exported is important on modern Android versions.

20. Cleaning and Rebuilding the Project

Cleaning removes generated build outputs. Rebuilding regenerates the outputs from the project's source code and configuration.

Use the Clean Project or Rebuild Project action when appropriate and available in your Android Studio version. You can also use Gradle tasks from the project terminal.

gradlew.bat clean
gradlew.bat assembleDebug

On macOS or Linux:

./gradlew clean
./gradlew assembleDebug

Cleaning is not a universal fix for every build problem. First identify the error. If it concerns incorrect source code, incompatible versions, or missing dependencies, fix that issue rather than repeatedly cleaning the project.

21. Common Troubleshooting Mistakes to Avoid

• Changing several configuration files before identifying the original error.
• Ignoring the first meaningful compiler or Gradle error.
• Assuming every warning is a fatal build failure.
• Installing an APK on a device without checking compatibility.
• Using an incompatible JDK, Gradle version, or Android Gradle Plugin combination.
• Deleting project files or caches without understanding the consequences.
• Ignoring Logcat when the app builds but crashes at runtime.
• Testing only the initial screen without checking button interactions and error states.
• Assuming a successful debug build means the release build is ready for publication.

22. Practical Project: Build and Run a Welcome App

Project Goal: Create a simple Android application that displays a welcome message and updates the message when a button is clicked.

Requirements

• Create a new Android Studio project using Kotlin.
• Display a welcome message on the main screen.
• Add a button labeled Click Me.
• Update the message after the button is clicked.
• Build the application successfully.
• Run the application on an emulator or physical device.
• Inspect Logcat if the application crashes.

Testing Checklist

• Confirm that Gradle synchronization completes.
• Confirm that the debug build succeeds.
• Confirm that the application installs and launches.
• Verify that the initial message is visible.
• Click the button and confirm that the message changes.
• Rotate the device if the layout supports rotation.
• Stop and relaunch the app to check its startup behavior.
• Record and resolve any errors discovered during testing.

Expected Result

The application should build without errors, launch on the selected Android device, display its initial welcome message, and respond to the button click. Any failures should be investigated using Build Output, Logcat, and the debugger.

23. Interview Questions and Answers

Q1. What is the difference between building and running an Android app?

Building processes the project's source code and resources to create application artifacts. Running usually builds the app if necessary, installs it on a target device, and launches it.

Q2. What is Gradle?

Gradle is a build automation system that executes tasks such as compilation, dependency resolution, testing, and packaging.

Q3. What is an APK?

An Android Package Kit is an installable package format used to distribute and install Android applications.

Q4. What is the difference between debug and release builds?

A debug build is intended primarily for development and testing, while a release build is configured for distribution and may use additional optimization and signing settings.

Q5. Where can you find Android build errors?

Use the Build tool window and its Build Output details. Gradle synchronization failures may also be visible in the Sync output.

Q6. What is Logcat used for?

Logcat displays system and application logs, including exceptions, crash messages, and diagnostic information useful for runtime troubleshooting.

Q7. What should you do when an app builds but crashes immediately?

Reproduce the crash, inspect Logcat for the exception and stack trace, locate the relevant application code, fix the underlying problem, and test again.

Q8. What is ADB?

Android Debug Bridge is a command-line tool that allows a computer to communicate with Android devices and emulators for tasks such as installation, shell access, and debugging support.

Q9. What is a Gradle synchronization error?

It occurs when Android Studio cannot successfully configure or resolve the project's build setup, often because of invalid configuration, incompatible versions, or dependency access problems.

Q10. Why should an app be tested on a physical device?

Physical devices help validate real hardware behavior, performance, manufacturer-specific differences, and features that an emulator may not reproduce accurately.

Q11. What is a breakpoint?

A breakpoint pauses application execution at a selected location so the developer can inspect variables, the call stack, and program behavior.

Q12. Does a successful debug build guarantee that the release build will succeed?

No. Release builds may use different signing settings, optimization rules, resource processing, and build configuration. Both build types should be verified when preparing an application for distribution.

24. Quick Revision Checklist

• Understand the Android project build and execution workflow.
• Know the purpose of Gradle and the Android Gradle Plugin.
• Distinguish debug builds from release builds.
• Build a debug APK using Android Studio or the Gradle Wrapper.
• Run the application on an emulator or physical device.
• Understand the role of AndroidManifest.xml.
• Use Build Output to investigate compilation and configuration errors.
• Use Logcat to investigate runtime errors and crashes.
• Use breakpoints and the debugger to inspect application execution.
• Test the app again after every meaningful fix.

25. Official Learning Resources

• Android Developers: Build and Run Your App
• Android Developers: Configure Your Build
• Android Developers: Debug Your App
• Android Developers: Android Debug Bridge (ADB)

26. Conclusion

Running, building, and troubleshooting the first Android application introduces the core workflow used throughout Android development. Developers must understand how source code, resources, Gradle configuration, and dependencies are transformed into an installable application. They must also learn to select a target device, deploy the app, verify its behavior, and investigate failures using Build Output, Logcat, and the debugger.

Practicing this workflow with a small application builds confidence and prepares developers to work on more advanced Android features, database integration, API communication, application architecture, and production-ready projects.

Explore the Course: Android App Development Training at JustAcademy

Register for a Demo: Book Your Course Demo

Visit the Website: JustAcademy